Ruotare le creatività degli annunci con l'API Select URL

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Utilizza l'API Select URL per sfruttare Shared Storage al fine di determinare la creatività visualizzata da un utente sui vari siti.

Un inserzionista o un produttore di contenuti potrebbe voler applicare strategie di rotazione dei contenuti diverse a una campagna e ruotare i contenuti o le creatività per aumentarne l'efficacia. L'API Select URL può essere utilizzata per eseguire diverse strategie di rotazione, ad esempio la rotazione sequenziale e la rotazione equa, su siti diversi.

Con la rotazione delle creatività dell'API Select URL, puoi memorizzare dati come ID creatività, conteggi delle visualizzazioni e interazioni utente per determinare quali creatività gli utenti visualizzano su siti diversi.

Per ulteriori informazioni sull'API sottostante e sul funzionamento della selezione, consulta la documentazione dell'API Select URL.

Provare la rotazione creatività

Per eseguire esperimenti sulla rotazione delle creatività, assicurati che l'API Select URL e Shared Storage siano abilitate:

• In chrome://settings/content/siteData, seleziona Allow sites to save data on your device o Delete data sites have saved to your device when you close all windows.
• In chrome://settings/adPrivacy/sites, seleziona Site-suggested ads.

Prova la nostra demo dal vivo di Shared Storage per una versione live degli esempi di codice in questo documento.

Demo con esempi di codice

In questo esempio:

• creative-rotation.js è lo script di terze parti che definisce i contenuti da ruotare, insieme a tutti i dati che determinano i contenuti successivi da selezionare e visualizzare, come i pesi in questo esempio. La pagina del publisher esegue questo script. Questo script chiama il worklet di archiviazione condivisa per determinare quali contenuti visualizzare in base ai dati disponibili nello spazio di archiviazione e all'elenco di URL da cui scegliere.

• creative-rotation-worklet.js è il worklet di archiviazione condiviso di terze parti che cerca la strategia di rotazione, calcola i contenuti da pubblicare successivamente e restituisce questi contenuti.

Come funziona la demo

1. Quando un utente visita la pagina del publisher, viene caricato lo script creative-rotation.js di terze parti. Lo script di rotazione delle creatività è responsabile del caricamento e dell'esecuzione del worklet di archiviazione condiviso. Lo script fornisce alla chiamata del worklet un elenco di URL tra cui scegliere.
2. Nel worklet, se lo spazio di archiviazione condiviso non è ancora stato inizializzato, viene inizializzato con la strategia di rotazione delle creatività e l'indice delle creatività iniziali. La strategia di rotazione iniziale utilizzata in questa demo è la strategia sequenziale.
3. Il worklet legge la modalità di rotazione dallo spazio di archiviazione condiviso e restituisce l'indice dell'annuncio successivo. Nel caso della modalità di rotazione sequenziale, aggiorna anche l'indice della creatività nello spazio di archiviazione condiviso con il nuovo valore da utilizzare per la chiamata successiva.Il worklet restituisce un oggetto URN FencedFrameConfig o opaco in base al valore resolveToConfig utilizzato quando si chiama selectURL.
4. Lo script di rotazione delle creatività mostra l'annuncio selezionato in un riquadro delimitato o in un iFrame. Per informazioni dettagliate sui tipi di valori restituiti, consulta la sezione Eseguire il rendering di un documento dell'annuncio.
5. Quando un utente modifica la modalità di rotazione, il worklet di archiviazione condivisa aggiorna il valore della modalità di rotazione della creatività memorizzato nello spazio di archiviazione condiviso.
6. Quando ricarichi la pagina del publisher, i passaggi da 1 a 4 vengono ripetuti per consentire la selezione dell'annuncio successivo da visualizzare in base alla strategia di rotazione selezionata.

Esempi di codice

Di seguito sono riportati gli esempi di codice per creative-rotation.js e creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Procedura dettagliata con screenshot

1. Per accedere alla rotazione delle creatività utilizzando l'API Select URL e lo spazio di archiviazione condiviso, vai alla pagina https://shared-storage-demo.web.app/. Scegli la demo "Rotazione creatività".

2. Scegli di esplorare la demo come "Publisher A". Verrà visualizzato il sito https://shared-storage-demo-publisher-a.web.app/creative-rotation. La pagina carica i contenuti numerati in base ai dati sulla rotazione delle creatività salvati in Shared Storage, a cui si accede tramite l'API Select URL. Le modalità demo per la rotazione delle creatività sono sequenziale, distribuzione uniforme e distribuzione ponderata. Il worklet esegue la logica per selezionare i contenuti visualizzati nell'iframe. L'immagine seguente mostra la pagina del publisher.

   
   

3. Per visualizzare i dati archiviati in Shared Storage, vai ad Applicazione -> Shared Storage in DevTools di Chrome. Vengono create due voci per lo spazio di archiviazione condiviso. È disponibile uno spazio di archiviazione vuoto per l'origine https://shared-storage-demo-publisher-a.web.app. Conterrà spazio di archiviazione specifico per l'origine e rimarrà vuoto per la nostra demo poiché il publisher non deve scrivere nello spazio di archiviazione condiviso. Tieni presente che verrà creato uno spazio di archiviazione simile per il publisher B quando visiterai la pagina in un secondo momento per la demo.

   
   

4. Verrà creata un'altra voce di Shared Storage per l'origine https://shared-storage-demo-content-producer.web.app. Si tratta dello spazio di archiviazione dell'iframe di terze parti incorporato nella pagina del publisher. Questo spazio di archiviazione verrà utilizzato per condividere i dati tra i due publisher disponibili al fine di coordinare la selezione delle creatività. Questo spazio di archiviazione condiviso verrà utilizzato per salvare le informazioni sulla creatività mostrata e sulla strategia di rotazione salvando due coppie chiave/valore. La prima chiave utilizzata nella demo è creative-rotation-index, il cui valore è l'indice corrente della creatività in modalità sequenziale. La seconda chiave è creative-rotation-mode, che determina la strategia di rotazione utilizzata.

   
   

5. Se aggiorni la pagina in modalità sequenziale, verrà visualizzata la creatività successiva nella sequenza 1, 2, 3, 1, … Il valore della chiave creative-rotation-index cambierà in base all'indice della creatività visualizzata in modalità sequenziale.

   
   

6. La modifica della modalità di rotazione delle creatività utilizzando i pulsanti di controllo aggiorna il valore della chiave creative-rotation-mode nella strategia corrispondente. Verrà utilizzato dal codice del worklet per scegliere la creatività successiva da mostrare nell'iframe. Tieni presente che il valore salvato per creative-rotation-index non cambia per le modalità di rotazione diverse da quella sequenziale.

   
   

7. Vai alla pagina di "Publisher B" all'indirizzo https://shared-storage-demo-publisher-b.web.app/creative-rotation. In modalità sequenziale, la creatività mostrata deve essere la creatività successiva della sequenza mostrata quando visiti l'URL di "Editore A". Se esamini lo spazio di archiviazione condiviso per il produttore di contenuti, puoi scoprire che sia "Publisher A" che "Publisher B" condividono lo stesso spazio di archiviazione e utilizzano le impostazioni presenti per selezionare la creatività successiva da mostrare e la strategia di rotazione da utilizzare.

   
   

8. Lo spazio di archiviazione condiviso per "Editore B" è vuoto, come per lo spazio di archiviazione condiviso di "Editore A".

   
   

   Casi d'uso

   Tutti i casi d'uso disponibili per l'API Select URL sono disponibili in questa sezione. Continueremo ad aggiungere esempi man mano che riceviamo feedback e scopriamo nuovi casi di test.

   • Ruota le creatività degli annunci: memorizza i dati, ad esempio l'ID creatività e l'interazione degli utenti, per determinare la creatività che gli utenti vedono su siti diversi.
   • Seleziona le creatività degli annunci in base alla frequenza: utilizza i dati sul conteggio delle visualizzazioni per determinare quali creatività vengono visualizzate dagli utenti su siti diversi.
   • Esegui test A/B: puoi assegnare un utente a un gruppo sperimentale, quindi archiviare il gruppo in Shared Storage per accedervi su più siti.
   • Personalizza l'esperienza per i clienti noti: condividi contenuti personalizzati e inviti all'azione in base allo stato di registrazione o ad altri stati dell'utente.

Coinvolgere e condividere feedback

Tieni presente che la proposta dell'API Select URL è in discussione e in fase di sviluppo ed è soggetta a modifiche.

Saremo lieti di conoscere la tua opinione sull'API Select URL.

• Proposta: esamina la proposta dettagliata.
• Discussione: partecipa alla discussione in corso per porre domande e condividere i tuoi approfondimenti.

Rimani al passo con le notizie

• Mailing list: iscriviti alla nostra mailing list per ricevere gli ultimi aggiornamenti e annunci relativi alle API Select URL e Shared Storage.

Hai bisogno di aiuto?

• Assistenza per gli sviluppatori: entra in contatto con altri sviluppatori e ricevi risposte alle tue domande nel repository Privacy Sandbox Developer Support.